# tools.bundlerChain

- **类型：**

```ts
type BundlerChainFn = (
  chain: RspackChain,
  utils: ModifyBundlerChainUtils,
) => Promise<void> | void;
```

- **默认值：** `undefined`

import RspackChain from '@zh/shared/rspackChain.mdx';

<RspackChain />

你可以通过 `tools.bundlerChain` 来调用 rspack-chain 以修改默认的 Rspack 配置，它的值是一个函数，接收两个参数：

- 第一个参数为 `rspack-chain` 实例，你可以通过它来修改 Rspack 配置。
- 第二个参数为一个工具对象，包括 `env`、`isProd`、`CHAIN_ID` 等。

> `tools.bundlerChain` 会早于 [tools.rspack](/config/tools/rspack) 被执行，因此会被 `tools.rspack` 覆盖。

:::tip
Rsbuild 内置的 Rspack 配置会随着迭代而发生变化，这些变化不会反映在 semver 中，因此在升级 Rsbuild 时，你的自定义配置可能会失效。
:::

## 示例

参考：[RspackChain 示例](/guide/basic/configure-rspack#使用-rspack-chain)。

## 工具对象

### env

- **类型：** `'development' | 'production' | 'test'`

通过 env 参数可以判断当前环境为 development、production 还是 test，比如：

```js
export default {
  tools: {
    bundlerChain: (chain, { env }) => {
      if (env === 'development') {
        chain.devtool('cheap-module-eval-source-map');
      }
    },
  },
};
```

### isDev

- **类型：** `boolean`

用于判断当前是否为开发模式构建，比如：

```js
export default {
  tools: {
    bundlerChain: (config, { isDev }) => {
      if (isDev) {
        config.devtool = 'eval-cheap-source-map';
      }
      return config;
    },
  },
};
```

### isProd

- **类型：** `boolean`

用于判断当前是否为生产模式构建，比如：

```js
export default {
  tools: {
    bundlerChain: (chain, { isProd }) => {
      if (isProd) {
        chain.devtool('source-map');
      }
    },
  },
};
```

### target

- **类型：** `'web' | 'node' | 'web-worker'`

通过 target 参数可以判断构建的目标运行时环境。比如：

```js
export default {
  tools: {
    bundlerChain: (chain, { target }) => {
      if (target === 'node') {
        // ...
      }
    },
  },
};
```

### isServer

- **类型：** `boolean`

判断当前构建的目标运行时环境是否为 `node`，等价于 `target === 'node'`。

```js
export default {
  tools: {
    bundlerChain: (chain, { isServer }) => {
      if (isServer) {
        // ...
      }
    },
  },
};
```

### isWebWorker

- **类型：** `boolean`

判断当前构建的目标运行时环境是否为 `web-worker`，等价于 `target === 'web-worker'`。

```js
export default {
  tools: {
    bundlerChain: (chain, { isWebWorker }) => {
      if (isWebWorker) {
        // ...
      }
    },
  },
};
```

### HtmlPlugin

- **类型：** `typeof import('html-rspack-plugin')`

通过这个参数你可以拿到 `html-rspack-plugin` 插件的实例。

```js
export default {
  tools: {
    bundlerChain: (chain, { HtmlPlugin }) => {
      console.log(HtmlPlugin);
    },
  },
};
```

## CHAIN_ID

Rsbuild 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。

:::tip
请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。

比如，`RULE.STYLUS` 仅在注册了 Stylus 插件后才会存在。
:::

### CHAIN_ID.RULE

| ID            | 描述                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `RULE.JS`     | 处理 `js` 和 `ts` 的规则                                                |
| `RULE.SVG`    | 处理 `svg` 的规则                                                       |
| `RULE.CSS`    | 处理 `css` 的规则                                                       |
| `RULE.LESS`   | 处理 `less` 的规则                                                      |
| `RULE.SASS`   | 处理 `sass` 的规则                                                      |
| `RULE.WASM`   | 处理 `wasm` 的规则                                                      |
| `RULE.FONT`   | 处理 `font` 的规则                                                      |
| `RULE.IMAGE`  | 处理 `image` 的规则                                                     |
| `RULE.MEDIA`  | 处理 `media` 的规则                                                     |
| `RULE.VUE`    | 处理 `vue` 的规则（依赖 [Vue 插件](/plugins/list/plugin-vue)）          |
| `RULE.SVELTE` | 处理 `svelte` 的规则（依赖 [Svelte 插件](/plugins/list/plugin-svelte)） |
| `RULE.STYLUS` | 处理 `stylus` 的规则（依赖 [Stylus 插件](/plugins/list/plugin-stylus)） |

### CHAIN_ID.ONE_OF

通过 `ONE_OF.[ID]` 可以匹配到规则数组中的某一类规则。

| ID                  | 描述                                                |
| ------------------- | --------------------------------------------------- |
| `ONE_OF.SVG_URL`    | 处理 SVG 的规则，输出为单独文件                     |
| `ONE_OF.SVG_INLINE` | 处理 SVG 的规则，作为 data URI 内联到 bundle 中     |
| `ONE_OF.SVG_ASSETS` | 处理 SVG 的规则，在 data URI 和单独文件之间自动选择 |

### CHAIN_ID.USE

通过 `USE.[ID]` 可以匹配到对应的 loader。

| ID                | 描述                                                                     |
| ----------------- | ------------------------------------------------------------------------ |
| `USE.SWC`         | 对应 `builtin:swc-loader`                                                |
| `USE.POSTCSS`     | 对应 `postcss-loader`                                                    |
| `USE.STYLE`       | 对应 `style-loader`                                                      |
| `USE.LESS`        | 对应 `less-loader`（依赖 [Less 插件](/plugins/list/plugin-less)）        |
| `USE.SASS`        | 对应 `sass-loader`（依赖 [Sass 插件](/plugins/list/plugin-sass)）        |
| `USE.RESOLVE_URL` | 对应 `resolve-url-loader`（依赖 [Sass 插件](/plugins/list/plugin-sass)） |
| `USE.VUE`         | 对应 `vue-loader`（依赖 [Vue 插件](/plugins/list/plugin-vue)）           |
| `USE.SVGR`        | 对应 `svgr-loader`（依赖 [Svgr 插件](/plugins/list/plugin-svgr)）        |
| `USE.BABEL`       | 对应 `babel-loader`（依赖 [Babel 插件](/plugins/list/plugin-babel)）     |
| `USE.SVELTE`      | 对应 `svelte-loader`（依赖 [Svelte 插件](/plugins/list/plugin-svelte)）  |
| `USE.STYLUS`      | 对应 `stylus-loader`（依赖 [Stylus 插件](/plugins/list/plugin-stylus)）  |

### CHAIN_ID.PLUGIN

通过 `PLUGIN.[ID]` 可以匹配到特定的 Rspack 或 Webpack plugin。

| ID                         | 描述                                                                              |
| -------------------------- | --------------------------------------------------------------------------------- |
| `PLUGIN.HTML`              | 对应 `HtmlRspackPlugin`，使用时需要拼接 entry 名称：`${PLUGIN.HTML}-${entryName}` |
| `PLUGIN.BUNDLE_ANALYZER`   | 对应 `WebpackBundleAnalyzer`                                                      |
| `PLUGIN.VUE_LOADER_PLUGIN` | 对应 `VueLoaderPlugin`（依赖 [Vue 插件](/plugins/list/plugin-vue)）               |

### CHAIN_ID.MINIMIZER

通过 `MINIMIZER.[ID]` 可以匹配到对应的压缩工具。

| ID              | 描述                                     |
| --------------- | ---------------------------------------- |
| `MINIMIZER.JS`  | 对应 `SwcJsMinimizerRspackPlugin`        |
| `MINIMIZER.CSS` | 对应 `LightningCssMinimizerRspackPlugin` |
